<html><!-- #BeginTemplate "/Templates/spydocs.dwt" -->
<head>
<!-- #BeginEditable "doctitle" --> 
<title>P6Spy Documentation</title>

<!-- #EndEditable -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body bgcolor="#FFFFFF">
<table width="100%" border="0" bgcolor="black">
<tr>
<td>
<img src="http://www.p6spy.com/documentation/images/header.gif" width="580" height="80"> 
<br> 
<table width="580" border="0">
  <tr> 
    <td width="11%"><a href="http://www.p6spy.com"><img src="http://www.p6spy.com/documentation/images/p6spy_com.gif" width="110" height="20" border="0"></a></td>
    <td width="11%"><a href="http://www.p6spy.com/documentation/index.htm"><img src="http://www.p6spy.com/documentation/images/index.gif" width="110" height="20" border="0"></a></td>
    <td width="11%"><a href="http://www.p6spy.com/documentation/install.htm"><img src="http://www.p6spy.com/documentation/images/install.gif" width="110" height="20" border="0"></a></td>
    <td width="11%"><a href="http://www.p6spy.com/documentation/other.htm#p6log"><img src="http://www.p6spy.com/documentation/images/p6log.gif" width="110" height="20" border="0"></a></td>
    <td width="11%"><a href="http://www.p6spy.com/documentation/other.htm#p6outage"><img src="http://www.p6spy.com/documentation/images/p6outage.gif" width="110" height="20" border="0"></a></td>
    <td width="38%">&nbsp;</td>
  </tr>
</table>
</td>
</tr>
</table>
<br>
<!-- #BeginEditable "body" --> 
<div align="center"> 
  <p><a name="install"></a><font face="Verdana, Arial, Helvetica, sans-serif" size="4"><b>Configuration 
    and Usage</b></font></p>
  <p>&nbsp;</p>
</div>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="4"><b><a name="common"></a></b></font><font face="Verdana, Arial, Helvetica, sans-serif" size="4"><b>Common 
  Property File Settings</b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">An example <b>spy.properties</b> 
  file follows:</font></p>
<p><font face="Courier New, Courier, mono" size="2"> #################################################################<br>
  # P6Spy Options File #<br>
  # See documentation for detailed instructions #<br>
  #################################################################</font></p>
<p><font face="Courier New, Courier, mono" size="2">#################################################################<br>
  # MODULES #<br>
  # #<br>
  # Modules provide the P6Spy functionality. If a module, such #<br>
  # as module_log is commented out, that functionality will not #<br>
  # be available. If it is not commented out (if it is active), #<br>
  # the functionality will be active. #<br>
  # #<br>
  # Values set in Modules cannot be reloaded using the #<br>
  # reloadproperties variable. Once they are loaded, they remain #<br>
  # in memory until the application is restarted. #<br>
  # #<br>
  #################################################################</font></p>
<p><font face="Courier New, Courier, mono" size="2">module.log=com.p6spy.engine.logging.P6LogFactory<br>
  #module.outage=com.p6spy.engine.outage.P6OutageFactory</font></p>
<p><font face="Courier New, Courier, mono" size="2">#################################################################<br>
  # REALDRIVER(s) #<br>
  # #<br>
  # In your application server configuration file you replace the #<br>
  # &quot;real driver&quot; name with com.p6spy.engine.P6SpyDriver. This is #<br>
  # where you put the name of your real driver P6Spy can find and #<br>
  # register your real driver to do the database work. #<br>
  # #<br>
  # If your application uses several drivers specify them in #<br>
  # realdriver2, realdriver3. See the documentation for more #<br>
  # details. #<br>
  # #<br>
  # Values set in REALDRIVER(s) cannot be reloaded using the #<br>
  # reloadproperties variable. Once they are loaded, they remain #<br>
  # in memory until the application is restarted. #<br>
  # #<br>
  #################################################################</font></p>
<p><font face="Courier New, Courier, mono" size="2"># oracle driver<br>
  # realdriver=oracle.jdbc.driver.OracleDriver</font></p>
<p><font face="Courier New, Courier, mono" size="2"># mysql Connector/J driver<br>
  realdriver=com.mysql.jdbc.Driver</font></p>
<p><font face="Courier New, Courier, mono" size="2"># informix driver<br>
  # realdriver=com.informix.jdbc.IfxDriver</font></p>
<p><font face="Courier New, Courier, mono" size="2"># ibm db2 driver<br>
  # realdriver=COM.ibm.db2.jdbc.net.DB2Driver</font></p>
<p><font face="Courier New, Courier, mono" size="2"># the mysql open source driver<br>
  # realdriver=org.gjt.mm.mysql.Driver</font></p>
<p><font face="Courier New, Courier, mono" size="2">#specifies another driver 
  to use<br>
  realdriver2=<br>
  #specifies a third driver to use<br>
  realdriver3=</font></p>
<p><font face="Courier New, Courier, mono" size="2">#the DriverManager class sequentially 
  tries every driver that is<br>
  #registered to find the right driver. In some instances, it's possible to<br>
  #load up the realdriver before the p6spy driver, in which case your connections<br>
  #will not get wrapped as the realdriver will &quot;steal&quot; the connection 
  before<br>
  #p6spy sees it. Set the following property to &quot;true&quot; to cause p6spy 
  to<br>
  #explicitily deregister the realdrivers<br>
  deregisterdrivers=false<br>
  <br>
  ################################################################<br>
  # P6LOG SPECIFIC PROPERTIES #<br>
  ################################################################<br>
  # no properties currently available</font></p>
<p>################################################################<br>
  # EXECUTION THRESHOLD PROPERTIES #<br>
  ################################################################<br>
  # This feature applies to the standard logging of P6Spy. # <br>
  # While the standard logging logs out every statement #<br>
  # regardless of its execution time, this feature puts a time # <br>
  # condition on that logging. Only statements that have taken # <br>
  # longer than the time specified (in milliseconds) will be #<br>
  # logged. This way it is possible to see only statements that #<br>
  # have exceeded some high water mark. #<br>
  # This time is reloadable. #<br>
  #<br>
  # executionthreshold=integer time (milliseconds)<br>
  #<br>
  executionthreshold=</p>
<p><font face="Courier New, Courier, mono" size="2">################################################################<br>
  # P6OUTAGE SPECIFIC PROPERTIES #<br>
  ################################################################<br>
  # Outage Detection<br>
  #<br>
  # This feature detects long-running statements that may be indicative of<br>
  # a database outage problem. If this feature is turned on, it will log any<br>
  # statement that surpasses the configurable time boundary during its execution.<br>
  # When this feature is enabled, no other statements are logged except the long<br>
  # running statements. The interval property is the boundary time set in seconds.<br>
  # For example, if this is set to 2, then any statement requiring at least 2 
  <br>
  # seconds will be logged. Note that the same statement will continue to be logged<br>
  # for as long as it executes. So if the interval is set to 2, and the query 
  takes<br>
  # 11 seconds, it will be logged 5 times (at the 2, 4, 6, 8, 10 second intervals).<br>
  #<br>
  # outagedetection=true|false<br>
  # outagedetectioninterval=integer time (seconds)<br>
  #<br>
  outagedetection=false<br>
  outagedetectioninterval=</font></p>
<p><font face="Courier New, Courier, mono" size="2">################################################################<br>
  # COMMON PROPERTIES #<br>
  ################################################################</font></p>
<p><font face="Courier New, Courier, mono" size="2"># comma separated list of 
  tables to include<br>
  include =<br>
  # comma separated list of tables to exclude<br>
  exclude =</font></p>
<p><font face="Courier New, Courier, mono" size="2"># sql expression to evaluate 
  if using regex<br>
  sqlexpression = </font></p>
<p><font face="Courier New, Courier, mono" size="2"># filter what is logged<br>
  filter=false </font></p>
<p><font face="Courier New, Courier, mono" size="2"># turn on tracing<br>
  trace = true<br>
  autoflush = true</font></p>
<p><font face="Courier New, Courier, mono" size="2"># sets the date format using 
  Java's SimpleDateFormat routine<br>
  dateformat=</font></p>
<p><font face="Courier New, Courier, mono" size="2">#list of categories to explicitly 
  include<br>
  includecategories=</font></p>
<p><font face="Courier New, Courier, mono" size="2">#list of categories to exclude: 
  error, info, batch, debug, statement,<br>
  #commit, rollback and result are valid values<br>
  #excludecategories=<br>
  excludecategories=info,debug,result,batch</font></p>
<p><font face="Courier New, Courier, mono" size="2">#allows you to use a regex 
  engine or your own matching engine to determine <br>
  #which statements to log<br>
  #<br>
  #stringmatcher=com.p6spy.engine.common.GnuRegexMatcher<br>
  #stringmatcher=com.p6spy.engine.common.JakartaRegexMatcher<br>
  stringmatcher=</font></p>
<p><font face="Courier New, Courier, mono" size="2"># prints a stack trace for 
  every statement logged<br>
  stacktrace=false<br>
  # if stacktrace=true, specifies the stack trace to print<br>
  stacktraceclass=</font></p>
<p><font face="Courier New, Courier, mono" size="2"># determines if property file 
  should be reloaded<br>
  reloadproperties=false<br>
  # determines how often should be reloaded in seconds<br>
  reloadpropertiesinterval=60</font></p>
<p><font face="Courier New, Courier, mono" size="2">#if=true then url must be 
  prefixed with p6spy:<br>
  useprefix=false</font></p>
<p><font face="Courier New, Courier, mono" size="2">#specifies the appender to 
  use for logging<br>
  #appender=com.p6spy.engine.logging.appender.Log4jLogger<br>
  #appender=com.p6spy.engine.logging.appender.StdoutLogger<br>
  appender=com.p6spy.engine.logging.appender.FileLogger</font></p>
<p><font face="Courier New, Courier, mono" size="2"># name of logfile to use, 
  note Windows users should make sure to use forward slashes in their pathname 
  (e:/test/spy.log) (used for file logger only)<br>
  logfile = spy.log</font></p>
<p><font face="Courier New, Courier, mono" size="2"># append to the p6spy log 
  file. if this is set to false the<br>
  # log file is truncated every time. (file logger only)<br>
  append=true</font></p>
<p><font face="Courier New, Courier, mono" size="2">#The following are for log4j 
  logging only<br>
  log4j.appender.STDOUT=org.apache.log4j.ConsoleAppender<br>
  log4j.appender.STDOUT.layout=org.apache.log4j.PatternLayout<br>
  log4j.appender.STDOUT.layout.ConversionPattern=p6spy - %m%n</font></p>
<p><font face="Courier New, Courier, mono" size="2">#log4j.appender.CHAINSAW_CLIENT=org.apache.log4j.net.SocketAppender<br>
  #log4j.appender.CHAINSAW_CLIENT.RemoteHost=localhost<br>
  #log4j.appender.CHAINSAW_CLIENT.Port=4445<br>
  #log4j.appender.CHAINSAW_CLIENT.LocationInfo=true</font></p>
<p><font face="Courier New, Courier, mono" size="2">log4j.logger.p6spy=INFO,STDOUT</font></p>
<p><font face="Courier New, Courier, mono" size="2">#################################################################<br>
  # DataSource replacement #<br>
  # #<br>
  # Replace the real DataSource class in your application server #<br>
  # configuration with the name com.p6spy.engine.spy.P6DataSource,#<br>
  # then add the JNDI name and class name of the real #<br>
  # DataSource here #<br>
  # #<br>
  # Values set in this item cannot be reloaded using the #<br>
  # reloadproperties variable. Once it is loaded, it remains #<br>
  # in memory until the application is restarted. #<br>
  # #<br>
  #################################################################<br>
  realdatasource=/RealMySqlDS<br>
  realdatasourceclass=com.mysql.jdbc.jdbc2.optional.MysqlDataSource</font></p>
<p><font face="Courier New, Courier, mono" size="2">#################################################################<br>
  # DataSource properties #<br>
  # #<br>
  # If you are using the DataSource support to intercept calls # <br>
  # to a DataSource that requires properties for proper setup, #<br>
  # define those properties here. Use name value pairs, separate #<br>
  # the name and value with a semicolon, and separate the #<br>
  # pairs with commas. #<br>
  # #<br>
  # The example shown here is for mysql #<br>
  # #<br>
  #################################################################<br>
  realdatasourceproperties=port;3306,serverName;myhost,databaseName;jbossdb,foo;bar</font></p>
<p><font face="Courier New, Courier, mono" size="2"><br>
  #################################################################<br>
  # JNDI DataSource lookup #<br>
  # #<br>
  # If you are using the DataSource support outside of an app #<br>
  # server, you will probably need to define the JNDI Context #<br>
  # environment. #<br>
  # #<br>
  # If the P6Spy code will be executing inside an app server then #<br>
  # do not use these properties, and the DataSource lookup will #<br>
  # use the naming context defined by the app server. #<br>
  # #<br>
  # The two standard elements of the naming environment are #<br>
  # jndicontextfactory and jndicontextproviderurl. If you need #<br>
  # additional elements, use the jndicontextcustom property. #<br>
  # You can define multiple properties in jndicontextcustom, #<br>
  # in name value pairs. Separate the name and value with a #<br>
  # semicolon, and separate the pairs with commas. #<br>
  # #<br>
  # The example shown here is for a standalone program running on #<br>
  # a machine that is also running JBoss, so the JDNI context #<br>
  # is configured for JBoss (3.0.4). #<br>
  # #<br>
  #################################################################<br>
  #jndicontextfactory=org.jnp.interfaces.NamingContextFactory<br>
  #jndicontextproviderurl=localhost:1099<br>
  #jndicontextcustom=java.naming.factory.url.pkgs;org.jboss.nameing:org.jnp.interfaces</font></p>
<p><font face="Courier New, Courier, mono" size="2">#jndicontextfactory=com.ibm.websphere.naming.WsnInitialContextFactory<br>
  #jndicontextproviderurl=iiop://localhost:900</font></p>
<p> <b><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><br>
  </font></b> <font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">module.xxx</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">module.xxx<b> </b>is 
  a particular module loaded at system startup. A module contains a group of functionality. 
  If a module line is not commented out, it is loaded into memory, and will remain 
  in memory until the application is restarted. Modules can not be changed by 
  using the reloadproperties function. If all modules are commented out, then 
  nothing except the wrapped database driver is loaded.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Currently the following 
  modules are supported:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">module.log=com.p6spy.engine.logging.P6LogSpyDriver<br>
    module.outage=com.p6spy.engine.outage.P6OutageSpyDriver</font></p>
</blockquote>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">module.log is required 
  for the logging functionality, see <a href="other.htm#p6log">P6Log</a>.<br>
  module.outage is required for the outage functionality, see <a href="other.htm#p6outage">P6Outage</a>.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">realdriver</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">realdriver is where 
  you specify the wrapped database driver.&nbsp;P6Spy wraps around your existing 
  driver, intercepts the incoming database requests, and outputs them to a log 
  file.&nbsp;To achieve this without requiring any code changes, the P6Spy driver 
  is listed with your application as the primary driver.&nbsp;P6Spy then intercepts 
  and logs the requests, and passes the requests to realdriver, where it is processed 
  as usual.&nbsp;An example follows:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">realdriver = oracle.jdbc.driver.OracleDriver</font></p>
</blockquote>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">realdriver2, 
  realdriver3 </font></b></font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">If you have multiple 
  database drivers, you need a way to specify these drivers. If you are using 
  the same database driver with multiple connection strings, you only need to 
  specify the driver once. For example, if you have two MySQL databases, mydb 
  and testdb, you want to connect to both databases and log their activity. Specify 
  <b>com.p6spy.engine.spy.P6SpyDriver</b> as the database driver for both of these 
  and set realdriver to the real MySQL JDBC driver name. realdriver2, realdriver3 
  are only intended for use when you are connecting with two different drivers, 
  for example Oracle versus MySQL.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">deregisterdrivers</font></b></font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">The DriverManager 
  class sequentially tries every driver that is registered to find the right driver. 
  In some instances, it's possible to load up the realdriver before the p6spy 
  driver, in which case your connections will not get wrapped as the realdriver 
  will &quot;steal&quot; the connection before p6spy sees it. Set the following 
  property to &quot;true&quot; to cause p6spy to explicitily deregister the realdrivers</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">filter, 
  include, exclude</font><u> </u></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">P6Spy allows you 
  to monitor specific tables or specific statement types.&nbsp;By setting <b>filter=true</b>, 
  P6Spy will perform string matching on each statement to determine if it should 
  be written to the log file.&nbsp;&nbsp;include accepts a comma-delimited list 
  of expressions which is required to appear in a statement before it can appear 
  in the log. exclude accepts a comma-delimited list to exclude. By default, string 
  matching is performed using a basic substring match. However, <font color="#000000">RegExp</font> 
  matching can also be used (see stringmatcher (Custom Filtering) below). Exclusion 
  overrides inclusion, so that a statement matching both an include string and 
  an exclude string is excluded. </font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">An example showing 
  capture of all select statements, except the orders table follows:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">filter = true<br>
    # comma separated list of tables to include<br>
    include = select<br>
    # comma separated list of tables to exclude<br>
    exclude = orders</font></p>
</blockquote>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">An example showing 
  only capture statements against order, order_details, price, and price_history 
  follows:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">filter = true<br>
    # comma separated list of tables to include<br>
    include = order,order_details,price,price_history<br>
    # comma separated list of tables to exclude<br>
    exclude =</font></p>
</blockquote>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">An example showing 
  the capture of all statements, except statements against the order table follows:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">filter = false<br>
    # comma separated list of tables to include<br>
    include = <br>
    # comma separated list of tables to exclude<br>
    exclude = order</font></p>
</blockquote>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">filter, 
  sqlexpression</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">If you plan on 
  using a <font color="#000000">RegExp </font>engine, a simple alternative to 
  exclude and include is to use sqlexpression. An example follows:</font></p>
<p><font face="Courier New, Courier, mono" size="2">filter = true<br>
  sqlexpression = your expression</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">If your expression 
  matches the SQL string, it is logged. If the expression does not match, it is 
  not logged. If you use sqlexpression, any values set in include and exclude 
  are ignored.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">stringmatcher 
  (Custom Filtering)</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"> If you want to 
  apply more intelligence to what is logged or not logged by P6Spy, you can specify 
  a custom matching engine. P6Spy comes with support for several <font color="#000000">RegExp</font> 
  engines, though it is trivial to introduce another engine by implementing the 
  stringmatcher interface. If a stringmatcher engine is specified, P6Spy will 
  pass each statement to the class specified to determine if that statement should 
  be logged.</font></p>
<ul>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><font color="#000000">Using 
    GNU</font><font color="#CC3333"> <font color="#000000">RegEx</font></font><font color="#000000">p</font>&#151;</font><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000">P6Spy 
    comes with support for a regular expression matcher based on the GNU RegExp 
    library.</font><font face="Verdana, Arial, Helvetica, sans-serif" size="2"> 
    In order to do this, <a href="http://www.cacas.org/java/gnu/regexp/">download</a> 
    the GNU Java RexExp library and add it to your classpath so that P6Spy can 
    find it. The following is an example of the implementation:</font> 
    <p><font face="Courier New, Courier, mono" size="2"># Use GNU Regex Matching 
      for Filtering<br>
      stringmatcher =com.p6spy.engine.common.GnuRegexMatcher</font><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><br>
      </font><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><br>
      </font></p>
  </li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Using Jakarta 
    RegExp&#151;P6Spy also includes support for the Apache Jakarta RegExp library. 
    In order to do this, <a href="http://jakarta.apache.org/builds/jakarta-regexp/">download</a> 
    the Apache Jarkarta RegExp library and add it to your classpath so that P6Spy 
    can find it.</font><font face="Verdana, Arial, Helvetica, sans-serif" size="2"> 
    The following is an example of the implementation:</font> 
    <p><font face="Courier New, Courier, mono" size="2"># Use Apache Jakarta Regex 
      Matching for Filtering<br>
      stringmatcher =com.p6spy.engine.common.JakartaRegexMatcher</font></p>
  </li>
</ul>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">autoflush</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">For standard development, 
  set the autoflush value to true. When set to true, every time a statement is 
  intercepted, it is immediately written to the log file.&nbsp;In some cases, 
  however, instant feedback on every statement is not a requirement. In those 
  cases, the system performs slightly faster with autoflush set to false.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">An example follows:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">autoflush = true</font><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><br>
    </font></p>
</blockquote>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3"><a name="appender"></a>appender</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Appenders allow 
  you to specify where and how log information is output. Appenders are a flexible 
  architecture allowing anyone to write their own output class for P6Spy. To use 
  an appender, specify the classname of the appender to use. The current release 
  comes with three options which are log4j, stdout, and logging to a CSV text 
  file (default).</font></p>
<ul>
  <li><font size="2" face="Verdana, Arial, Helvetica, sans-serif">Using a CSV 
    File&#151;</font><font size="2" face="Verdana, Arial, Helvetica, sans-serif">To 
    output to a file, uncomment the FileLogger appender and specify a logfile 
    and whether or not to append to the file or to clear the file each time: </font> 
    <p><font size="2" face="Courier New, Courier, mono">#appender=com.p6spy.engine.logging.appender.Log4jLogger<br>
      #appender=com.p6spy.engine.logging.appender.StdoutLogger<br>
      appender=com.p6spy.engine.logging.appender.FileLogger</font></p>
    <p><font size="2" face="Courier New, Courier, mono"># name of logfile to use, 
      note Windows users should make sure to use forward slashes in their pathname(e:/test/spy.log) 
      (used for file logger only)<br>
      logfile = spy.log</font></p>
    <p><font size="2" face="Courier New, Courier, mono"># append to the p6spy 
      log file. if this is set to false the<br>
      # log file is truncated every time. (file logger only)<br>
      append=true</font></p>
  </li>
  <li><font size="2" face="Verdana, Arial, Helvetica, sans-serif">Using StdOut&#151;</font><font size="2" face="Verdana, Arial, Helvetica, sans-serif">Uncomment 
    the StdoutLogger as follows and all output will be sent to stdout in a CSV 
    format:</font> 
    <p><font size="2" face="Courier New, Courier, mono">#appender=com.p6spy.engine.logging.appender.Log4jLogger<br>
      appender=com.p6spy.engine.logging.appender.StdoutLogger<br>
      #appender=com.p6spy.engine.logging.appender.FileLogger</font></p>
  </li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Using Log4J&#151;</font><font size="2" face="Verdana, Arial, Helvetica, sans-serif">To 
    output to log4j, make sure log4j is in your path, uncomment the log4j appender, 
    and specify the desired log4j settings:</font> 
    <p><font size="2" face="Courier New, Courier, mono">appender=com.p6spy.engine.logging.appender.Log4jLogger<br>
      #appender=com.p6spy.engine.logging.appender.StdoutLogger<br>
      # appender=com.p6spy.engine.logging.appender.FileLogger</font></p>
    <p><font size="2" face="Courier New, Courier, mono">#The following are for 
      log4j logging only<br>
      log4j.appender.STDOUT=org.apache.log4j.ConsoleAppender<br>
      log4j.appender.STDOUT.layout=org.apache.log4j.PatternLayout<br>
      log4j.appender.STDOUT.layout.ConversionPattern=p6spy - %m%n</font></p>
    <p><font size="2" face="Courier New, Courier, mono">#log4j.appender.CHAINSAW_CLIENT=org.apache.log4j.net.SocketAppender<br>
      #log4j.appender.CHAINSAW_CLIENT.RemoteHost=localhost<br>
      #log4j.appender.CHAINSAW_CLIENT.Port=4445<br>
      #log4j.appender.CHAINSAW_CLIENT.LocationInfo=true</font></p>
    <p><font size="2" face="Courier New, Courier, mono">log4j.logger.p6spy=INFO,STDOUT</font></p>
    <p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">If for some 
      reason log4j cannot be initialized, the logging will go to a file called 
      <b>log4jaux.log</b>.</font></p>
  </li>
</ul>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">excludecategories</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">The log includes 
  category information that describes the type of statement. This property excludes 
  the listed categories. Valid options include the following:</font></p>
<ul>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000"><strong>error</strong> 
    includes P6Spy errors. (It is recommended that you include this category.)</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000"><strong>info</strong> 
    includes driver startup information and property file information. </font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000"><strong>debug 
    </strong>is only intended for use when you cannot get your driver to work 
    properly, because it writes everything.</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000"><strong>statement 
    </strong> includes Statements, PreparedStatements, and CallableStatements.<strong> 
    </strong></font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#CC0033"><strong><font color="#000000">batch</font></strong><font color="#000000"> 
    includes calls made to the addBatch() JDBC API.</font></font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000"><strong>commit</strong> 
    includes calls made to the commit() JDBC API.</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000"><strong>rollback</strong> 
    includes calls made to the rollback() JDBC API.</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#CC0033"><strong><font color="#000000">result</font></strong><font color="#000000"> 
    includes statements generated by ResultSet.</font></font></li>
</ul>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Enter a comma-delimited 
  list of categories to exclude from your log file. See filter, include, exclude 
  for more details on how this process works.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">includecategories</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">includecategories 
  includes category information that describes the type of statement. This property 
  is a comma-delimited list of categories to include. See excludecategories for 
  a valid list of categories.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">dateformat</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Setting a value 
  for dateformat changes the date format value printed in the log file. No value 
  prints the current time in milliseconds, a useful feature for parsing the log. 
  The date format engine is Java's SimpleDateFormat class. Refer to the SimpleDateFormat 
  class in the JavaDocs for information on setting this value. </font><font face="Verdana, Arial, Helvetica, sans-serif" size="2">An 
  example follows: </font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">dateformat=MM-dd-yy HH:mm:ss:SS</font></p>
</blockquote>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">stacktrace</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">If stacktrace is 
  set, the log prints out the stack trace for each SQL statement logged.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">stacktraceclass</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Limits the stack 
  traces printed to those that contain the value set in stacktraceclass. For example, 
  specifying <b>stacktraceclass=com.mycompany.myclass </b> limits the printing 
  of stack traces to the specified class value. The stack trace is converted to 
  a String and string.indexOf(stacktraceclass) is performed.</font><br>
  <b><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><br>
  </font></b> <font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">reloadproperties 
  and reloadpropertiesinterval</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">If reloadproperties 
  is set to true, the property file is reloaded every <i>n</i> seconds, where 
  <i>n</i> is defined by the value set by reloadpropertiesinterval. For example, 
  if <b>reloadproperties=true</b> and <b>reloadpropertiesinterval=10</b>,<b> </b> 
  the system checks the File.lastModified() property of the property file every 
  10 seconds, and if the file has been modified, it will be reloaded.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">If you set <b>append=true</b>, 
  the log will be suddenly truncated when you change your properties. This is 
  because using reloadproperties is intended to be the equivalent of restarting 
  your application server. Restarting your application server truncates your log 
  file.</font></p>
<p><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><b>reloadproperties</b> 
  will not reload any driver information (such as realdriver, realdriver2, and 
  realdriver3) and will not change the modules that are in memory.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">useprefix</font></b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Setting useprefix 
  to <b>true</b> requires you to prefix your URLs with <b>p6spy:</b>. The default 
  setting is <b>false</b>.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font size="3">Command 
  Line Options</font> </b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Every parameter 
  specified in the property file can be set and overriden at the command line 
  using the Java <b>-</b>D flag.</font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">An example follows:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">java -Dp6logfile=my.log 
    -Dp6trace=true</font></p>
</blockquote>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">In addition, you 
  can set the default directory to look for <b>spy.properties</b>, as shown in 
  the following example:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">java -Dp6.home=c:\orion\lib</font></p>
</blockquote>
<p><a name="log"></a><font face="Verdana, Arial, Helvetica, sans-serif" size="4"><b>Log 
  File Format</b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">The log file format 
  of <b>spy.log</b> follows:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">current time|execution time|category|statement 
    SQL String|effective SQL string</font></p>
</blockquote>
<ul>
  <li><b><font face="Verdana, Arial, Helvetica, sans-serif" size="2">current time</font></b><font face="Courier New, Courier, mono" size="2">&#151;</font><font face="Verdana, Arial, Helvetica, sans-serif" size="2">The 
    current time is obtained through System.getCurrentTimeMillis() and represents 
    the number of milliseconds that have passed since January 1, 1970 00:00:00.000 
    GMT. (Refer to the J2SE documentation for further details on System.getCurrentTimeMillis().) 
    <font color="#000000">To change the format, </font><font color="#000000">use 
    the dateformat property described in <a href="other.htm">Common Property File 
    Settings</a>.</font></font></li>
  <li><b><font face="Verdana, Arial, Helvetica, sans-serif" size="2">execution 
    time</font></b><font face="Verdana, Arial, Helvetica, sans-serif" size="2">&#151;The 
    time it takes for a particular method to execute. (This is not the total cost 
    for the SQL statement.) For example, a statement SELECT * FROM MYTABLE WHERE 
    THISCOL = ? might be executed as a prepared statement, in which the .execute() 
    function will be measured. This is recorded as the statement category. Further, 
    as you call .next() on the ResultSet, each .next()<b> </b>call is recorded 
    in the result category.</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b>category</b></font><font face="Courier New, Courier, mono" size="2">&#151;</font><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><font color="#000000">You 
    can manage your log by including and excluding categories, which is described 
    in </font><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><font color="#000000"><a href="other.htm">Common 
    Property File Settings</a></font></font><font color="#000000">. </font></font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b>statement 
    SQL string</b>&#151;This is the SQL string passed to the statement object. 
    If it is a prepared statement, it is the prepared statement that existed prior 
    to the parameters being set. To see the complete statement, refer to effective 
    SQL string<font face="Verdana, Arial, Helvetica, sans-serif">.</font></font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b>effective 
    SQL string</b></font><font face="Courier New, Courier, mono" size="2">&#151;</font><font face="Verdana, Arial, Helvetica, sans-serif" size="2">If 
    you are not using a prepared statement, this contains no value. Otherwise, 
    it fills in the values of the Prepared Statement so you can see the effective 
    SQL statement that is passed to the database. Of course, the database still 
    sees the prepared statement, but this string is a convenient way to see the 
    actual values <font color="#000000">being sent to the database.</font></font></li>
</ul>
<p><a name="jsp"></a><font face="Verdana, Arial, Helvetica, sans-serif" size="4"><b>The 
  JSP Application</b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">P6Spy includes 
  a JSP application. Use this application to view P6Spy configuration information 
  and to create a demarcation in the log file. To use the JSP application, complete 
  the following steps:</font></p>
<ol>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Copy <b>p6spy.war</b> 
    into the deployment directory of your application server. In JBoss, for example, 
    the directory might be C:\JBoss-2.4.4_Tomcat-4.0.1\jboss\deploy. </font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Once <b>p6spy.war</b> 
    is deployed, access the application by navigating to http://<i>machine</i>:<i>port</i>/p6spy. 
    For example, if you are running the application on your own machine, and using 
    Tomcat as the servlet engine, navigate to http://localhost:8080/p6spy.</font></li>
</ol>
<p><a name="jboss_jmx"></a><font face="Verdana, Arial, Helvetica, sans-serif" size="4"><b>The 
  JBoss JMX Application</b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">P6Spy includes 
  a JMX application, tested with JBoss 2.4.x, that allows the P6Spy configuration 
  to be managed via JMX. To use this </font></p>
<ol>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">In <strong>spy.properties</strong> 
    set reloadproperties=true</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Open <strong>JBoss.jcml</strong> 
    and insert the following after the &quot;JMX Adaptors&quot; section:</font></li>
  <blockquote> 
    <p><font face="Courier New, Courier, mono" size="2"> &lt;mbean code=&quot;com.p6spy.management.jboss.P6SpyManager&quot; 
      name=&quot;:service=P6SpyManager&quot;/&gt;</font></p>
  </blockquote>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Access the application 
    by using the default JMX port (http://localhost:8082/) and clicking on &quot;service=P6SpyManager&quot;.</font></li>
</ol>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="4"><b><a name="build" id="faq"></a>Building 
  the Source </b></font></p>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">To build the source, 
  complete the following steps:</font></p>
<ol>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2"> <a href="http://jakarta.apache.org/ant/index.html">Download 
    Jakarta Ant</a>. </font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Install Jakarta 
    Ant.</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><font color="#000000">You 
    must also download some required libraries.</font><font color="#CC0033"> </font>Running 
    Ant the first time will display a message listing all required libraries and 
    locations where they can be downloaded. </font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Copy these libraries 
    into the<b> </b>lib directory, which is a subdirectory of your main directory 
    (the directory with the source code). </font></li>
</ol>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">The following are 
  useful Ant targets:</font></p>
<ul>
  <li><font color="#CC3333"><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b><font color="#000000">ant</font></b><font color="#000000"> 
    creates a<b> p6spy.jar</b> file in the dist directory.</font></font></font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000"><b>ant 
    clean</b> cleans the directory of build files and tool-generated backup files.</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000"> 
    <b>ant release</b> creates the Javadocs, the .war file, and all distribution 
    .zip and .jar files.</font></li>
  <li><b><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000">ant 
    test</font></b><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000"> 
    runs the standard JUnit tests. Refer to the JUnit test instructions below.</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2" color="#000000"><b>ant 
    perform</b> runs the performance specific JUnit tests.</font></li>
</ul>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">To run the JUnit 
  tests, complete the following steps:</font></p>
<ol>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><a href="http://www.junit.org/index.htm">Download 
    JUnit</a>.</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Install JUnit</font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Edit the <b>P6Test.properties</b> 
    file and specify two databases. The configuration is set up for Oracle and 
    MySQL. You must change the Oracle URL, at minimum. </font></li>
  <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2">Copy the vendor 
    database JDBC drivers' JAR files (of the two databases) into the lib directory.</font> 
  </li>
</ol>
<div align="center"> 
  <p align="left"><a name="modules"></a><font face="Verdana, Arial, Helvetica, sans-serif" size="4"><b>P6Spy 
    Modules</b></font></p>
</div>
<p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">P6Spy consists 
  of two modules that provide various types of functionality which can be modified 
  to suit your needs.</font><font size="2" face="Verdana, Arial, Helvetica, sans-serif" color="#000000"> 
  These modules, P6Log and P6Outage, are explained in this section of the documentation. 
  Though they have distinct functions, they share some common property file settings 
  that allow you to specify which tables to log, the log file name, the log file 
  location, whether to show the stacktrace (where the JDBC statement is being 
  executed), and more.</font><font size="2" face="Verdana, Arial, Helvetica, sans-serif" color="#CC0000"> 
  </font><font size="2" face="Verdana, Arial, Helvetica, sans-serif">Refer to 
  the <a href="other.htm#common">Common Property File Settings</a> documentation 
  for details. </font></p>
<blockquote> 
  <p><font face="Verdana, Arial, Helvetica, sans-serif" size="3"><a name="p6log"></a><b>P6Log</b></font></p>
  <p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">P6Log is an open-source 
    application included in the P6Spy distribution that intercepts and logs the 
    database statements of any application that uses JDBC. This application monitors 
    the SQL statements produced by EJB servers, enabling developers to write code 
    that achieves maximum efficiency on the server. The P6Log module is enabled 
    by default. Disable or enable the P6Log module by editing the <b>spy.properties</b> 
    configuration file. If the module is commented out, it is not loaded, and 
    the functionality is not available. If the module is not commented out, the 
    functionality is available. The applicable portion of the <b>spy.properties</b> 
    file follows:</font></p>
  <blockquote> 
    <pre><font face="Courier New, Courier, mono" size="2">#################################################################<br>
    # MODULES #<br>
    # #<br>
    # Modules provide the P6Spy functionality. If a module, such #<br>
    # as module_log is commented out, that functionality will not #<br>
    # be available. If it is not commented out (if it is active), #<br>
    # the functionality will be active. #<br>
    # #<br>
    # Values set in Modules cannot be reloaded using the #<br>
    # reloadproperties variable. Once they are loaded, they remain #<br>
    # in memory until the application is restarted. #<br>
    # #<br>
    #################################################################</font></pre>
    <pre><font face="Courier New, Courier, mono" size="2">module.log=com.p6spy.engine.logging.P6LogSpyDriver<br>
#module.outage=com.p6spy.engine.outage.P6OutageSpyDriver</font></pre>
  </blockquote>
  <p>&nbsp;</p>
  <p><font size="3"><a name="p6outage"></a><font face="Verdana, Arial, Helvetica, sans-serif"><b>P6Outage</b></font></font></p>
  <p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">P6Outage is an 
    open-source application included in the P6Spy distribution. P6Outage minimizes 
    any logging performance overhead by logging only long-running statements. 
    The P6Outage module is disabled by default. Disable or enable the P6Outage 
    module by editing the <b>spy.properties</b> configuration file. If the module 
    is commented out, it is not loaded, and the functionality is not available. 
    If the module is not commented out, the functionality is available.</font></p>
  <p><font face="Verdana, Arial, Helvetica, sans-serif" size="2">The applicable 
    portion of the <b>spy.properties</b> file follows:</font></p>
  <blockquote> 
    <pre><font face="Courier New, Courier, mono" size="2">#################################################################<br>
    # MODULES #<br>
    # #<br>
    # Modules provide the P6Spy functionality. If a module, such #<br>
    # as module_log is commented out, that functionality will not #<br>
    # be available. If it is not commented out (if it is active), #<br>
    # the functionality will be active. #<br>
    # #<br>
    # Values set in Modules cannot be reloaded using the #<br>
    # reloadproperties variable. Once they are loaded, they remain #<br>
    # in memory until the application is restarted. #<br>
    # #<br>
    #################################################################</font></pre>
    <pre><font face="Courier New, Courier, mono" size="2">#module.log=com.p6spy.engine.logging.P6LogSpyDriver<br>
module.outage=com.p6spy.engine.outage.P6OutageSpyDriver</font></pre>
  </blockquote>
  <p>&nbsp;</p>
  <p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">The following 
    are P6Outage-specific properties:</font></p>
  <ul>
    <li><font face="Verdana, Arial, Helvetica, sans-serif" size="2"><b>outagedetection</b></font> 
      <p><font face="Verdana, Arial, Helvetica, sans-serif" size="2"></font> <font size="2" face="Verdana, Arial, Helvetica, sans-serif">This 
        feature detects long-running statements that may be indicative of a database 
        outage problem. When enabled, it logs any statement that surpasses the 
        configurable time boundary during its execution. No other statements are 
        logged except the long-running statements.</font></p>
    </li>
    <li><font size="2" face="Verdana, Arial, Helvetica, sans-serif"><strong>outagedetectioninterval</strong></font> 
      <p><font size="2" face="Verdana, Arial, Helvetica, sans-serif">The interval 
        property is the boundary time set in seconds. For example, if set to 2, 
        any statement requiring at least 2 seconds is logged. The same statement 
        will continue to be logged for as long as it executes. So, if the interval 
        is set to 2 and a query takes 11 seconds, it is logged 5 times (at the 
        2, 4, 6, 8, 10-second intervals).</font></p>
    </li>
  </ul>
</blockquote>
<p>&nbsp;</p>
<ol>
  <blockquote> 
    <div align="left"></div>
  </blockquote>
</ol>
<!-- #EndEditable --> <br>
<table width="100%" border="0" bgcolor="black">
<tr>
<td>
<table width="580" border="0">
  <tr> 
    <td width="11%"><a href="http://www.p6spy.com"><img src="http://www.p6spy.com/documentation/images/p6spy_com.gif" width="110" height="20" border="0"></a></td>
    <td width="11%"><a href="http://www.p6spy.com/documentation/index.htm"><img src="http://www.p6spy.com/documentation/images/index.gif" width="110" height="20" border="0"></a></td>
    <td width="11%"><a href="http://www.p6spy.com/documentation/install.htm"><img src="http://www.p6spy.com/documentation/images/install.gif" width="110" height="20" border="0"></a></td>
    <td width="11%"><a href="http://www.p6spy.com/documentation/p6spymodules.htm#p6log"><img src="http://www.p6spy.com/documentation/images/p6log.gif" width="110" height="20" border="0"></a></td>
    <td width="11%"><a href="http://www.p6spy.com/documentation/p6spymodules.htm#p6outage"><img src="http://www.p6spy.com/documentation/images/p6outage.gif" width="110" height="20" border="0"></a></td>
    <td width="38%">&nbsp;</td>
  </tr>
</table>
</td>
</tr>
</table>
</body>
<!-- #EndTemplate --></html>
